home *** CD-ROM | disk | FTP | other *** search
/ Grand Slam / GrandSlam volume 1.iso / 018 / midimod2.arj / MOD-FORM.TXT < prev    next >
Text File  |  1993-06-28  |  18KB  |  363 lines

  1. Noisetracker/Soundtracker/Protracker Module Format
  2. --------------------------------------------------
  3. Credits:  Lars Hamre, Norman Lin, Mark Cox, Peter Hanning, and
  4.           Steinar Midtskogen
  5. (All numbers below are given in decimal)
  6.           1st Revision
  7.  
  8. Module Format:
  9. # Bytes   Description
  10. -------   -----------
  11. 20        The module's title, padded with null (\0) bytes. Original
  12.           Protracker wrote letters only in uppercase.
  13.  
  14. (Data repeated for each sample 1-15 or 1-31)
  15. 22        Sample's name, padded with null bytes. If a name begins with a
  16.           '#', it is assumed not to be an instrument name, and is
  17.           probably a message.
  18. 2         Sample length in words (1 word = 2 bytes). The first word of
  19.           the sample is overwritten by the tracker, so a length of 1
  20.           still means an empty sample. See below for sample format.
  21. 1         Lowest four bits represent a signed nibble (-8..7) which is
  22.           the finetune value for the sample. Each finetune step changes
  23.           the note 1/8th of a semitone. Implemented by switching to a
  24.           different table of period-values for each finetune value.
  25. 1         Volume of sample. Legal values are 0..64. Volume is the linear
  26.           difference between sound intensities. 64 is full volume, and
  27.           the change in decimals can be calculated with 20*log10(Vol/64)
  28. 2         Start of sample repeat offset in words. Once the sample has
  29.           been played all of the way through, it will loop if the repeat
  30.           length is greater than one. It repeats by jumping to this
  31.           position in the sample and playing for the repeat length, then
  32.           jumping back to this position, and playing for the repeat
  33.           length, etc.
  34. 2         Length of sample repeat in words. Only loop if greater than 1.
  35. (End of this sample's data.. each sample uses the same format and they
  36.  are stored sequentially)
  37. NB. All 2 byte lengths are stored with the Hi-byte first, as is usual on
  38.     the Amiga (big-endian format).
  39.  
  40. 1         Number of song positions (ie. number of patterns played
  41.           throughout the song). Legal values are 1..128.
  42. 1         Historically set to 127, but can be safely ignored.
  43.           Noisetracker uses this byte to indicate restart position -
  44.           this has been made redundant by the 'Position Jump' effect.
  45. 128       Pattern table: patterns to play in each song position (0..127)
  46.           Each byte has a legal value of 0..63 (note the Protracker
  47.           exception below). The highest value in this table is the
  48.           highest pattern stored, no patterns above this value are
  49.           stored.
  50. (4)       The four letters "M.K." These are the initials of Mahoney &
  51.           Kaktus and were introduced along with the increase to 31
  52.           samples. Startrekker puts "FLT4" or "FLT8" here to indicate
  53.           the # of channels. If there are more than 64 patterns,
  54.           Protracker will put "M!K!" here. If no letters are here, then
  55.           this is the start of the pattern data, and only 15 samples are
  56.           present.
  57.  
  58. (Data repeated for each pattern:)
  59. 1024      Pattern data for each pattern (starting at 0).
  60. (Each pattern has same format and is stored in numerical order.
  61.  See below for pattern format)
  62.  
  63. (Data repeated for each sample:)
  64. xxxxxx    The maximum size of a sample is 65535 words. Each sample is
  65.           stored as a collection of bytes (length of a sample was given
  66.           previously in the module). Each byte is a signed value (-128
  67.           ..127) which is the channel data. When a sample is played at a
  68.           pitch of C2 (see below for pitches), about 8287 bytes of
  69.           sample data are sent to the channel per second. Multiply the
  70.           rate by the twelfth root of 2 (=1.0595) for each semitone
  71.           increase in pitch eg. moving the pitch up 1 octave doubles the
  72.           rate. The data is stored in the order it is played (eg. first
  73.           byte is first byte played). The first word of the sample data
  74.           is used to hold repeat information, and will overwrite any
  75.           sample data that is there (but it is probably safter to set it
  76.           to 0).
  77.           The rate given above (8287) conveys an inaccurate picture of
  78.           the module-format - in reality it is different for different
  79.           Amigas. As the routines for playing were written to run off
  80.           certain interrupts, for different Amiga computers the rate to
  81.           send data to the channel will be different. For PAL machines
  82.           the clock rate is 7093789.2 Hz and for NTSC machines it is
  83.           7159090.5 Hz. When the clock rate is divided by twice the
  84.           period number for the pitch it will give the rate to send the
  85.           data to the channel, eg. for a PAL machine sending a note at
  86.           C2 (period 428), the rate is 7093789.2/856 ~= 8287.1369
  87. (Each sample is stored sequentially)
  88.  
  89. Pattern Format:
  90. Each pattern is divided into 64 divisions. By allocating different
  91. tempos for each pattern and spacing the notes across different amounts
  92. of divisions, different bar sizes can be accomodated.
  93.  
  94. Each division contains the data for each channel (1..4) stored after
  95. each other. Each channel's data in the division has an identical format
  96. which consists of 2 words (4 bytes). Divisions are numbered 0..63. Each
  97. division may be divided into a number of ticks (see 'set speed' effect
  98. below).
  99.  
  100. Channel Data:
  101.                    (the four bytes of channel data in a pattern divison)
  102. 7654-3210 7654-3210 7654-3210 7654-3210
  103. wwww xxxxxxxxxxxxxx yyyy zzzzzzzzzzzzzz
  104.  
  105.     wwwwyyyy (8 bits) is the sample for this channel/division
  106. xxxxxxxxxxxx (12 bits) is the sample's period (or effect parameter)
  107. zzzzzzzzzzzz (12 bits) is the effect for this channel/division
  108.  
  109. If there is to be no new sample to be played at this division on this
  110. channel, then the old sample on this channel will continue, or at least
  111. be "remembered" for any effects. If the sample is 0, then the previous
  112. sample on that channel is used. Only one sample may play on a channel at
  113. a time, so playing a new sample will cancel an old one - even if there
  114. has been no data supplied for the new sample. Though, if you are using a
  115. "silence" sample (ie. no data, only used to turn off other samples) it
  116. is polite to set its default volume to 0.
  117.  
  118. To determine what pitch the sample is to be played on, look up the
  119. period in a table, such as the one below (for finetune 0). If the period
  120. is 0, then the previous period on that channel is used. It is best to do
  121. a binary-search (unless you use the period as the offset of an array of
  122. notes.. expensive), especially if you plan to use periods outside the
  123. "standard" range. Periods are the internal representation of the pitch,
  124. so effects that alter pitch (eg. sliding) alter the period value (see
  125. "effects" below).
  126.  
  127.           C    C#   D    D#   E    F    F#   G    G#   A    A#   B
  128. Octave 1: 856, 808, 762, 720, 678, 640, 604, 570, 538, 508, 480, 453
  129. Octave 2: 428, 404, 381, 360, 339, 320, 302, 285, 269, 254, 240, 226
  130. Octave 3: 214, 202, 190, 180, 170, 160, 151, 143, 135, 127, 120, 113
  131.  
  132. Octave 0:1712,1616,1525,1440,1357,1281,1209,1141,1077,1017, 961, 907
  133. Octave 4: 107, 101,  95,  90,  85,  80,  76,  71,  67,  64,  60,  57
  134.  
  135. Octaves 0 and 4 are NOT standard, so don't rely on every tracker being
  136. able to play them, or even not crashing if being given them - it's just
  137. nice that if you can code it, to allow them to be read.
  138.  
  139. Effects:
  140. Effects are written as groups of 4 bits, eg. 1871 = 7 * 256 + 4 * 16 +
  141. 15 = [7][4][15]. The high nibble (4 bits) usually determines the effect,
  142. but if it is [14], then the second nibble is used as well.
  143.  
  144. [0]: Arpeggio
  145.      Where [0][x][y] means "play note, note+x semitones, note+y
  146.      semitones, then return to original note". The fluctuations are
  147.      carried out evenly spaced in one pattern division. They are usually
  148.      used to simulate chords, but this doesn't work too well. They are
  149.      also used to produce heavy vibrato. A major chord is when x=4, y=7.
  150.      A minor chord is when x=3, y=7.
  151.  
  152. [1]: Slide up
  153.      Where [1][x][y] means "smoothly decrease the period of current
  154.      sample by x*16+y after each tick in the division". The
  155.      ticks/division are set with the 'set speed' effect (see below). If
  156.      the period of the note being played is z, then the final period
  157.      will be z - (x*16 + y)*(ticks - 1). As the slide rate depends on
  158.      the speed, changing the speed will change the slide. You cannot
  159.      slide beyond the note B3 (period 113).
  160.  
  161. [2]: Slide down
  162.      Where [2][x][y] means "smoothly increase the period of current
  163.      sample by x*16+y after each tick in the division". Similar to [1],
  164.      but lowers the pitch. You cannot slide beyond the note C1 (period
  165.      856).
  166.  
  167. [3]: Slide to note
  168.      Where [3][x][y] means "smoothly change the period of current sample
  169.      by x*16+y after each tick in the division, never sliding beyond
  170.      current period". The period-length in this channel's division is a
  171.      parameter to this effect, and hence is not played. Sliding to a
  172.      note is similar to effects [1] and [2], but the slide will not go
  173.      beyond the given period, and the direction is implied by that
  174.      period. If [x] and [y] are both 0, then the old slide will
  175.      continue.
  176.  
  177. [4]: Vibrato
  178.      Where [4][x][y] means "oscillate the sample pitch using a
  179.      particular waveform with amplitude y/16 semitones, such that (x *
  180.      ticks)/64 cycles occur in the division". The waveform is set using
  181.      effect [14][4]. By placing vibrato effects on consecutive
  182.      divisions, the vibrato effect can be maintained. If either [x] or
  183.      [y] are 0, then the old vibrato values will be used.
  184.  
  185. [5]: Continue 'Slide to note', but also do Volume slide
  186.      Where [5][x][y] means "either slide the volume up x*(ticks - 1) or
  187.      slide the volume down y*(ticks - 1), at the same time as continuing
  188.      the last 'Slide to note'". It is illegal for both x and y to be
  189.      non-zero. You cannot slide outside the volume range 0..64. The
  190.      period-length in this channel's division is a parameter to this
  191.      effect, and hence is not played.
  192.  
  193. [6]: Continue 'Vibrato', but also do Volume slide
  194.      Where [6][x][y] means "either slide the volume up x*(ticks - 1) or
  195.      slide the volume down y*(ticks - 1), at the same time as continuing
  196.      the last 'Vibrato'". It is illegal for both x and y to be non-zero.
  197.      You cannot slide outside the volume range 0..64.
  198.  
  199. [7]: Tremolo
  200.      Where [7][x][y] means "oscillate the sample volume using a
  201.      particular waveform with amplitude y*(ticks - 1), such that (x *
  202.      ticks)/64 cycles occur in the division". The waveform is set using
  203.      effect [14][7]. Similar to [4].
  204.  
  205. [8]: -- Unused --
  206.  
  207. [9]: Set sample offset
  208.      Where [9][x][y] means "play the sample from offset x*4096 + y*256".
  209.      The offset is measured in words. If no sample is given, yet one is
  210.      still playing on this channel, it should be retriggered to the new
  211.      offset using the current volume.
  212.  
  213. [10]: Volume slide
  214.      Where [10][x][y] means "either slide the volume up x*(ticks - 1) or
  215.      slide the volume down y*(ticks - 1)". It is illegal for both x and
  216.      y to be non-zero. You cannot slide outside the volume range 0..64.
  217.  
  218. [11]: Position Jump
  219.      Where [11][x][y] means "stop the pattern after this division, and
  220.      continue the song at song-position x*16+y". This shifts the
  221.      'pattern-cursor' in the pattern table (see above). Legal values for
  222.      x*16+y are from 0 to 127.
  223.  
  224. [12]: Set volume
  225.      Where [12][x][y] means "set current sample's volume to x*16+y".
  226.      Legal volumes are 0..64.
  227.  
  228. [13]: Pattern Break
  229.      Where [13][x][y] means "stop the pattern after this division, and
  230.      continue the song at the next pattern at division x*10+y" (the 10
  231.      is not a typo). Legal divisions are from 0 to 63.
  232.  
  233. [14][0]: Set filter on/off
  234.      Where [14][0][x] means "set sound filter ON if x is 0, and OFF is x
  235.      is 1". This is a hardware command for some Amigas, so if you don't
  236.      understand it, it is better not to use it.
  237.  
  238. [14][1]: Fineslide up
  239.      Where [14][1][x] means "decrement the period of the current sample
  240.      by x". The incrementing takes place at the beginning of the
  241.      division, and hence there is no actual sliding. You cannot slide
  242.      beyond the note B3 (period 113).
  243.  
  244. [14][2]: Fineslide down
  245.      Where [14][2][x] means "increment the period of the current sample
  246.      by x". Similar to [14][1] but shifts the pitch down. You cannot
  247.      slide beyond the note C1 (period 856).
  248.  
  249. [14][3]: Set glissando on/off
  250.      Where [14][3][x] means "set glissando ON if x is 1, OFF if x is 0".
  251.      Used in conjunction with [3] ('Slide to note'). If glissando is on,
  252.      then 'Slide to note' will slide in semitones, otherwise will
  253.      perform the default smooth slide.
  254.  
  255. [14][4]: Set vibrato waveform
  256.      Where [14][4][x] means "set the waveform of succeeding 'vibrato'
  257.      effects to wave #x". [4] is the 'vibrato' effect.  Possible values
  258.      for x are:
  259.           0 - sine (default)      /\    /\     (2 cycles shown)
  260.           4  (without retrigger)     \/    \/
  261.  
  262.           1 - ramp down          | \   | \
  263.           5  (without retrigger)     \ |   \ |
  264.  
  265.           2 - square             ,--,  ,--,
  266.           6  (without retrigger)    '--'  '--'
  267.  
  268.           3 - random
  269.           7  (without retrigger)
  270.      If the waveform is selected "without retrigger", then it will not
  271.      be retriggered from the beginning at the start of each new note.
  272.  
  273. [14][5]: Set finetune value
  274.      Where [14][5][x] means "sets the finetune value of the current
  275.      sample to the signed nibble x". x has legal values of 0..15,
  276.      corresponding to signed nibbles 0..7,-8..-1 (see start of text for
  277.      more info on finetune values).
  278.  
  279. [14][6]: Loop pattern
  280.      Where [14][6][x] means "set the start of a loop to this division if
  281.      x is 0, otherwise after this division, jump back to the start of a
  282.      loop and play it another x times before continuing". If the start
  283.      of the loop was not set, it will default to the start of the
  284.      current pattern. Hence 'loop pattern' cannot be performed across
  285.      multiple patterns. Note that loops do not support nesting, and you
  286.      may generate an infinite loop if you try to nest 'loop pattern's.
  287.  
  288. [14][7]: Set tremolo waveform
  289.      Where [14][7][x] means "set the waveform of succeeding 'tremolo'
  290.      effects to wave #x". Similar to [14][4], but alters effect [7] -
  291.      the 'tremolo' effect.
  292.  
  293. [14][8]: -- Unused --
  294.  
  295. [14][9]: Retrigger sample
  296.      Where [14][9][x] means "trigger current sample every x ticks in
  297.      this division". If x is 0, then no retriggering is done (acts as if
  298.      no effect was chosen), otherwise the retriggering begins on the
  299.      first tick and then x ticks after that, etc.
  300.  
  301. [14][10]: Fine volume slide up
  302.      Where [14][10][x] means "increment the volume of the current sample
  303.      by x". The incrementing takes place at the beginning of the
  304.      division, and hence there is no sliding. You cannot slide beyond
  305.      volume 64.
  306.  
  307. [14][11]: Fine volume slide down
  308.      Where [14][11][x] means "decrement the volume of the current sample
  309.      by x". Similar to [14][10] but lowers volume. You cannot slide
  310.      beyond volume 0.
  311.  
  312. [14][12]: Cut sample
  313.      Where [14][12][x] means "after the current sample has been played
  314.      for x ticks in this division, its volume will be set to 0". This
  315.      implies that if x is 0, then you will not hear any of the sample.
  316.      If you wish to insert "silence" in a pattern, it is better to use a
  317.      "silence"-sample (see above) due to the lack of proper support for
  318.      this effect.
  319.  
  320. [14][13]: Delay sample
  321.      Where [14][13][x] means "do not start this division's sample for
  322.      the first x ticks in this division, play the sample after this".
  323.      This implies that if x is 0, then you will hear no delay, but
  324.      actually there will be a VERY small delay. Note that this effect
  325.      only influences a sample if it was started in this division.
  326.  
  327. [14][14]: Delay pattern
  328.      Where [14][14][x] means "after this division there will be a delay
  329.      equivalent to the time taken to play x divisions after which the
  330.      pattern will be resumed". The delay only relates to the
  331.      interpretting of new divisions, and all effects and previous notes
  332.      continue during delay.
  333.  
  334. [14][15]: Invert loop
  335.      Where [14][15][x] means "if x is greater than 0, then play the
  336.      current sample's loop upside down at speed x". Each byte in the
  337.      sample's loop will have its sign changed (negated). It will only
  338.      work if the sample's loop (defined previously) is not too big. The
  339.      speed is based on an internal table.
  340.  
  341. [15]: Set speed
  342.      Where [15][x][y] means "set speed to x*16+y". Though it is not that
  343.      simple. Let z = x*16+y. z=0 should technically cause the module to
  344.      stop. If z<32 then it means "set ticks/division to z" otherwise it
  345.      means "set beats/min to z". Though some strange trackers also set
  346.      beats/min to 750/z if z<32. Default values are 6 ticks/division,
  347.      and 125 beats/min (4 divisions = 1 beat). It is best to not mix the
  348.      different types of "set speed" in a single division, as I have seen
  349.      4 different trackers act 4 different ways when mixing them, though
  350.      the proper way is the obvious way.
  351.  
  352. NB. This document should be fairly accurate now (being the 1st revision)
  353. but as the module format is more of an observation than a standard, a
  354. couple of effects cannot be relied upon to act the same from tracker to
  355. tracker (especially if the tracker is not for the Amiga). It is probably
  356. better to use this document as a guide rather than as a hard-and-fast
  357. definition of the module format. Oh.. and yes, I would normally give
  358. bytes as hex values, but it is easier to understand a consistant
  359. notation.
  360.  
  361. Andrew Scott (Adrenalin Software), INTERNET:ascott@tartarus.uwa.edu.au
  362. Author of MIDIMOD (MOD to MIDI converter).
  363.